home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Tech Arsenal 1
/
Tech Arsenal (Arsenal Computer).ISO
/
tek-02
/
strg61b.zip
/
STRGREF.DOC
< prev
next >
Wrap
Text File
|
1991-06-17
|
91KB
|
1,961 lines
STRG UTILITIES
REFERENCE GUIDE
Version 6.1b
June 17, 1991
Copyright (C) 1989-1991 Eagle Performance Software
All Rights Reserved.
_______
____|__ | (tm)
--| | |-------------------
| ____|__ | Association of
| | |_| Shareware
|__| o | Professionals
-----| | |---------------------
|___|___| MEMBER
STRG Utilities Reference Guide, Version 6.1b
T A B L E O F C O N T E N T S
1. INTRODUCTION . . . . . . . . . . . . . . . . . . . . . 4
Purpose . . . . . . . . . . . . . . . . . . . . . . . 4
Parameters . . . . . . . . . . . . . . . . . . . . . 4
Code Size . . . . . . . . . . . . . . . . . . . . . . 5
Speed . . . . . . . . . . . . . . . . . . . . . . . . 5
2. PROCEDURES AND FUNCTIONS . . . . . . . . . . . . . . . 6
AscStr . . . . . . . . . . . . . . . . . . . . . . . 6
ChrDel* . . . . . . . . . . . . . . . . . . . . . . . 6
ChrFill . . . . . . . . . . . . . . . . . . . . . . . 7
ChrPad* . . . . . . . . . . . . . . . . . . . . . . . 7
ChrPos* . . . . . . . . . . . . . . . . . . . . . . . 7
ChrQty* . . . . . . . . . . . . . . . . . . . . . . . 8
ChrRepl* . . . . . . . . . . . . . . . . . . . . . . 8
Copy . . . . . . . . . . . . . . . . . . . . . . . . 9
Delete . . . . . . . . . . . . . . . . . . . . . . . 9
Is* . . . . . . . . . . . . . . . . . . . . . . . . . 9
LnStr . . . . . . . . . . . . . . . . . . . . . . . . 10
LoCase . . . . . . . . . . . . . . . . . . . . . . . 11
Pos . . . . . . . . . . . . . . . . . . . . . . . . . 11
StrAsc . . . . . . . . . . . . . . . . . . . . . . . 11
StrLn . . . . . . . . . . . . . . . . . . . . . . . . 12
Str* . . . . . . . . . . . . . . . . . . . . . . . . 12
StrBin . . . . . . . . . . . . . . . . . . . . . . . 13
StrBrk . . . . . . . . . . . . . . . . . . . . . . . 13
StrCat* . . . . . . . . . . . . . . . . . . . . . . . 13
StrCmp* . . . . . . . . . . . . . . . . . . . . . . . 14
StrCopy . . . . . . . . . . . . . . . . . . . . . . . 14
StrCut . . . . . . . . . . . . . . . . . . . . . . . 15
StrDeTab . . . . . . . . . . . . . . . . . . . . . . 15
StrEnum . . . . . . . . . . . . . . . . . . . . . . . 15
StrFill . . . . . . . . . . . . . . . . . . . . . . . 15
StrHex . . . . . . . . . . . . . . . . . . . . . . . 16
StrIns . . . . . . . . . . . . . . . . . . . . . . . 16
StrJ* . . . . . . . . . . . . . . . . . . . . . . . . 17
StrLwr . . . . . . . . . . . . . . . . . . . . . . . 17
StrMemb . . . . . . . . . . . . . . . . . . . . . . . 17
StrMove . . . . . . . . . . . . . . . . . . . . . . . 18
StrOvr . . . . . . . . . . . . . . . . . . . . . . . 18
StrPeek . . . . . . . . . . . . . . . . . . . . . . . 18
StrPoke . . . . . . . . . . . . . . . . . . . . . . . 19
StrPos* . . . . . . . . . . . . . . . . . . . . . . . 19
StrQty* . . . . . . . . . . . . . . . . . . . . . . . 20
StrRepl* . . . . . . . . . . . . . . . . . . . . . . 20
StrReTab . . . . . . . . . . . . . . . . . . . . . . 21
StrRev . . . . . . . . . . . . . . . . . . . . . . . 21
StrRoll . . . . . . . . . . . . . . . . . . . . . . . 21
StrSort . . . . . . . . . . . . . . . . . . . . . . . 22
StrSpn . . . . . . . . . . . . . . . . . . . . . . . 22
StrUpr . . . . . . . . . . . . . . . . . . . . . . . 23
UpCase . . . . . . . . . . . . . . . . . . . . . . . 23
2
STRG Utilities Reference Guide, Version 6.1b
ValBin . . . . . . . . . . . . . . . . . . . . . . . 23
ValHex . . . . . . . . . . . . . . . . . . . . . . . 23
Wrd* . . . . . . . . . . . . . . . . . . . . . . . . 24
WrdParse . . . . . . . . . . . . . . . . . . . . . . 25
WrdPos* . . . . . . . . . . . . . . . . . . . . . . . 25
WrdQty . . . . . . . . . . . . . . . . . . . . . . . 26
WrdToken . . . . . . . . . . . . . . . . . . . . . . 26
3. VARIABLES . . . . . . . . . . . . . . . . . . . . . . . 28
Global . . . . . . . . . . . . . . . . . . . . . . . 28
Local . . . . . . . . . . . . . . . . . . . . . . . . 29
4. ACCESSIBLE MEMORY . . . . . . . . . . . . . . . . . . . 30
5. QUICK REFERENCE . . . . . . . . . . . . . . . . . . . . 31
3
STRG Utilities Reference Guide, Version 6.1b
1. I N T R O D U C T I O N
PURPOSE
This document is a STRG technical reference manual describing each routine
and variable in detail in a format similar to the Borland manual. The
routines are described in alphabetical order. Since this manual is on
disk, you can find your interest easily with a search utility.
Application - All STRG procedures process strings with high-speed optimized
assembly code. To be as fast as possible, almost all routines are
procedures rather than functions to increase speed 2 to 3 times.
PARAMETERS
Common Parameters - Most procedures use the same parameters. Rather than
repeating them for each routine, detailed descriptions for those parameters
are listed below.
Count - number of characters or substrings to copy.
Decimals - number of digits to the right of the decimal.
Dest - Pascal destination string (as opposed to source).
Field - number of digits in the field.
Find - a character or substring to find in a source string.
Index - the starting offset in the Pascal source string.
MaxLen - the maximum length permitted for the resulting string to
prevent overwriting memory.
Nth - process until the "Nth" occurrence.
Repl - replacement character or substring.
S - Pascal source string.
Source - Pascal source string (as opposed to destination).
Order of Parameters - Of course not all of these parameters may be used,
but the order of the parameters is consistent throughout the routines.
Here is the general order:
1. Destination - such as Dest
2. Source - such as S and Source
3. Substrings - such as Find, Repl, Fill, First, and Last
4. Index - always of the source
5. Count - such as Count, Field, Nth and Qty
6. Maximum - maximum length of destination string
This arrangement matches that of C. For procedures, if there is a
destination, it is always the first parameter; just like the assignment,
(":=") the destination is always on the left.
Index - All index parameters are 1-based. If a zero is entered, it is
converted to 1. The Delete procedure is the only exception to this, but it
is part of standard Pascal.
Chapter 1, Introduction Page 4
STRG Utilities Reference Guide, Version 6.1b
CODE SIZE
Unit Size - If you use a STRG procedure, only the corresponding object file
containing that procedure will be linked and thereby optimizing the code.
| Even if all 111 procedures are used, STRG is still quite small at a total
| of about 6.3k bytes. In all, there are 78 object files used to create the
| unit which is about 5900 lines of assembly or 250k of code.
Code Usage - This Shareware unit has been released with the $N+ and $E+
compiler directives set. This means that an additional 12k of code is
included for the IEEE reals library inserted by the compiler. The IEEE
reals are used in the Str* numeric formatting functions and are enabled for
your testing. Should you not want to use these functions and are a
registered user, you can turn off these directives at the beginning of the
STRG unit. This will drop the IEEE library from the executable code.
SPEED
Speed Bench - How fast is fast? To have a basis for comparison, a unit of
strings-per-second (str/sec) is used for a relative measure of speed. To
get this rating, a routine is repeated with a FOR loop to operate on a
given string and any "reset" of the original string is subtracted out as
overhead. The RATE61.PAS program can duplicate this for you so you can
bench test your own routines for actual speed. Overall, if you use STRG
for your application, your speeds will easily be 3 times faster or more.
Relative Speed - The ratings mentioned in the Reference Manual are speeds
obtained from actual bench test on an 80386 / 20 MHz machine. Granted,
that this may be faster than most units, but the important aspect of these
ratings is relative speed. By comparing ratings with other routines in
this unit, you can judge how to best assemble a program technique that can
suit your needs.
Processing Rating - Not only can machines vary in speed, but the string
values in your program are complete variables. When given a routine like
StrPosL, the test performed is on an 80-character string with a 5-letter
word at the end of the string. So the test forces the routine to search
the entire string. This provides a worst case scenario to give you a feel
for the length of time for an operation. Similarly, StrPosR is tested with
the 5-letter word at the beginning of the string and so the ratings for
both routines are about the same. But one of these routines may be much
better for your program from a strategic standpoint. So, the rating
provided gives one of processing performance and not from the perspective
that a better rating means faster speed for your application.
Chapter 1, Introduction Page 5
STRG Utilities Reference Guide, Version 6.1b
2. P R O C E D U R E S A N D F U N C T I O N S
In this section, a detailed description is provided for each procedure and
function.
---------------------------------------------------------------------------
AscStr procedure Strg
---------------------------------------------------------------------------
Function Creates ASCIIZ strings from Pascal-type strings.
Declaration AscStr (VAR AscDest; S: string)
Remarks After AscStr is executed, the global variable AscDestPtr is
updated to point to the next destination address just after
the null. Source and destination can be the same. As in
all move-type procedures, it is important to make sure the
destination size is sufficient to fit the source.
Rating 42,900 str/sec
See also LnStr, StrAsc and the variable AscDestPtr.
Example Pack three Pascal strings into an array of ASCIIZ strings.
uses strg;
var
S: array[0..4] of string;
A: array[0..26] of char;
i: byte;
begin
S[1] := 'Eagle';
S[2] := 'Performance';
S[3] := 'Software';
AscDestPtr := @A;
for i:=1 to 3 do
AscStr (AscDestPtr^,S[i]);
end.
The resulting array A would look like:
'Eagle'#00'Performance'#00'Software'#00
---------------------------------------------------------------------------
ChrDel* procedure Strg
---------------------------------------------------------------------------
Function Operates on a string to delete a given character.
Declaration ChrDel (VAR S: string; Find: char)
ChrDelL (VAR S: string; Find: char)
ChrDelR (VAR S: string; Find: char)
Remarks ChrDel deletes all finds in the entire string.
ChrDelL deletes only left (or leading) finds.
ChrDelR deletes only right (or trailing) finds.
Rating ChrDel: 9,400 str/sec
ChrDelL: 39,000 str/sec
ChrDelR: 132,000 str/sec
See also StrCut
Example Try these examples:
Chapter 2, Procedures and Functions Page 6
STRG Utilities Reference Guide, Version 6.1b
MyString := ' more info ';
MyNumStr := '1,234,567';
ChrDel (MyNumStr,','); { MyNumStr='1234567' }
ChrDelL (MyString,' '); { MyString='more info ' }
ChrDelR (MyString,' '); { MyString='more info' }
---------------------------------------------------------------------------
ChrFill procedure Strg
---------------------------------------------------------------------------
Function Fills a string with multiple copies of a character.
Declaration ChrFill (VAR S: string; Fill: char; Count: byte)
Remarks The fill overwrites S with Count number of repetitions of
Fill and automatically sets the length byte. Be sure the
destination is large enough. Up to twice as fast as using
system.fillchar.
Rating 53,400 str/sec
See also StrEnum, StrFill
Example Try the following example:
ChrFill (S,'a',5); { S='aaaaa' }
---------------------------------------------------------------------------
ChrPad* procedure Strg
---------------------------------------------------------------------------
Function Pads a string on the left, right, or to center with a given
character to fill a field.
Declaration ChrPadC (VAR S: string; Fill: char; Field: byte)
ChrPadL (VAR S: string; Fill: char; Field: byte)
ChrPadR (VAR S: string; Fill: char; Field: byte)
Remarks ChrPadC pads left and right to center the field.
ChrPadL pads on the left (or leading) fill.
ChrPadR pads on the right (or trailing) fill.
Rating ChrPadC: 36,500 str/sec
ChrPadL: 42,900 str/sec
ChrPadR: 52,000 str/sec
See also ChrDel, StrCut, StrJ*
Example Try these examples:
MyStr := 'abcdefgh'; { 12345678901 }
ChrPadC (MyStr,'*',11); { MyStr='*abcdefgh**' }
ChrPadL (MyStr,'=',11); { MyStr='===abcdefgh' }
ChrPadR (MyStr,' ',11); { MyStr='abcdefgh ' }
---------------------------------------------------------------------------
ChrPos* function Strg
---------------------------------------------------------------------------
Function Finds the position of a given character with match/ignore
case.
Declaration ChrPosL (S: string; Find: char; Nth: byte)
ChrPosLI (S: string; Find: char; Nth: byte)
ChrPosR (S: string; Find: char; Nth: byte)
ChrPosRI (S: string; Find: char; Nth: byte)
ChrPosX (S: string; Find: char; indeX: byte)
ChrPosXI (S: string; Find: char; indeX: byte)
Chapter 2, Procedures and Functions Page 7
STRG Utilities Reference Guide, Version 6.1b
Result type byte
Remarks Using suffixes, -L routine searches from the left while the
-R searches from the right for the Nth occurrence. The -X
routine starts at the given index and searches right for the
first occurrence. These routines match case, while those
with the added -I suffix will Ignore case.
Rating ChrPos?: 25,400 str/sec
ChrPos?I: 22,500 str/sec (non-alphabetic Find)
ChrPos?I: 10,200 str/sec (alphabetic Find)
See also StrBrk, StrPos*
Example Try the following examples:
S1 := 'C:\MySubDir\SubDir#2\myfile';
S2 := 'Eagle Performance Software';
MyByte := ChrPosR (S1,'\',1); { MyByte=21 }
MyByte := ChrPosLI (S2,'e',3); { MyByte= 8 }
MyByte := ChrPosXI (S2,'s',8); { MyByte=19 }
---------------------------------------------------------------------------
ChrQty* function Strg
---------------------------------------------------------------------------
Function Counts the occurrences of a given character in
a string with match/ignore case.
Declaration ChrQty (S: string; Find: char)
ChrQtyI (S: string; Find: char)
Result type byte
Remarks ChrQty matches case while ChrQtyI ignores case.
Rating ChrQty: 23,100 str/sec
ChrQtyI: 22,500 str/sec (non-alphabetic Find)
ChrQtyI: 10,200 str/sec (alphabetic Find)
See also StrQty*, WrdQty
Example Given a string, S:='Eagle Performance Software', try the
following examples:
MyByte := ChrQty (S,'a'); { MyByte=3 }
MyByte := ChrQtyI (S,'e'); { MyByte=5 }
---------------------------------------------------------------------------
ChrRepl* procedure Strg
---------------------------------------------------------------------------
Function Finds and replaces a character from a given index for a
specified number of replacements with match/ignore case.
Declaration ChrRepl (VAR S: string; Find,Repl: char; Index,Qty: byte)
ChrReplI (VAR S: string; Find,Repl: char; Index,Qty: byte)
Remarks The operation starts from Index and goes to the right. It
will stop if the index is beyond the end of string or it has
replaced as many as it can. ChrRepl matches case while
ChrReplI ignores case.
Rating ChrRepl: 21,300 str/sec
ChrReplI: 20,300 str/sec (non-alphabetic Find)
ChrReplI: 10,000 str/sec (alphabetic Find)
See also ChrDel*, StrRepl*
Example Try the following example:
Chapter 2, Procedures and Functions Page 8
STRG Utilities Reference Guide, Version 6.1b
S := '/s -12 -cga /off';
ChrRepl (S,'-','/',1,255); { S='/s /12 /cga /off' }
---------------------------------------------------------------------------
Copy function Strg
---------------------------------------------------------------------------
Function Returns a substring of a string.
Declaration Copy (S: string; Index,Count: integer)
Result type string
Remarks It's the exact replacement of the System.Copy function, but
automatically replaces it with one that is up to 34% faster.
Rating 21,500 str/sec
See also StrCopy, StrOvr, Compiler reference manual
---------------------------------------------------------------------------
Delete procedure Strg
---------------------------------------------------------------------------
Function Deletes a substring from a string.
Declaration Delete (VAR S: string; Index,Count: integer)
Remarks It's the exact replacement of the System.Delete procedure,
but automatically replaces it with one that is up to 5 times
faster.
Rating 39,300 str/sec
See also ChrDel*, StrCut, Compiler reference manual
---------------------------------------------------------------------------
Is* function Strg
---------------------------------------------------------------------------
Function Character classification function.
Declaration IsAlNum (C: char) { Alpha-numeric }
IsAlpha (C: char) { Upper and lower case letters }
IsASCII (C: char) { Lower ASCII table }
IsCntrl (C: char) { Print control characters }
IsDigit (C: char) { 0 through 9 }
IsDos (C: char) { Valid DOS directory & wildcards }
IsFile (C: char) { Valid DOS file name }
IsGraph (C: char) { Black characters }
IsLower (C: char) { Lower case letters }
IsPath (C: char) { Valid DOS path & drive & subdirs }
IsPrint (C: char) { Printable characters }
IsPunct (C: char) { Punctuation marks }
IsReal (C: char) { Real numbers }
IsSigned (C: char) { Signed integers }
IsSpace (C: char) { Space or line control }
IsUpper (C: char) { Upper case letters }
IsXDigit (C: char) { Hex digits }
Result type boolean
Remarks These exactly duplicate the C implementation of character
classification, but a few are unique to STRG. The best
balance of speed and code is used for each one and they are
more efficient than the use of sets. All functions only
consider characters in the lower ASCII table (<#128). The
function will return TRUE if the following characters are
passed (the "-" means through):
Chapter 2, Procedures and Functions Page 9
STRG Utilities Reference Guide, Version 6.1b
IsAlNum: 0-9 A-Z a-z
IsAlpha: A-Z a-z
IsASCII: Less than #128
IsCntrl: #00-#31 #127
IsDigit: 0-9
IsDos: ! #-* #45 #46 0-: ?-Z \ ^-{ }-~
IsFile: ! #-) #45 #46 0-9 @-Z ^-{ }-~
IsGraph: #33-#126
IsLower: a-z
IsPath: ! #-) #45 #46 0-: @-Z \ ^-{ }-~
IsPrint: #32-#126
IsPunct: IsGraph but not IsAlNum
IsReal: 0-9 + Minus . e E
IsSigned: 0-9 + Minus
IsSpace: Space #09-#13
IsUpper: A-Z
IsXDigit: 0-9 A-F a-f
IsDos checks for characters that are valid when asking for a
directory at the DOS command prompt such as:
C:\MySubDir\Subdir#2\All?.*
IsPath is the same as IsDos except it doesn't accept the
wildcards '*' and '?'. IsFile is the the same as IsPath
except it will not accept the drive and path characters ':'
and '\'.
See also StrMemb
Example Create a membership string containing only valid Real number
characters:
S := '';
for MyChar:='+' to 'e' do
if IsReal (MyChar) then
StrCat (S,MyChar,255); { S='+-.0123456789Ee' }
---------------------------------------------------------------------------
LnStr procedure Strg
---------------------------------------------------------------------------
Function Creates ASCII TEXT strings from Pascal-type strings.
Declaration LnStr (VAR LnDest; S: string)
Remarks LnStr copies the characters of string S to the line
destination Ln and terminates the line with a CR/LF
(#13/#10). After StrLn is executed, the global variable
LnDestPtr points to the next destination after the CR/LF.
As in all move-type procedures, it is important to make sure
the destination size is sufficient to fit the source.
Suggestions The use of WriteLn for text files is disk intensive. LnStr
can be used together with BlockWrite for extremely fast text
file operations.
Rating 42,200 str/sec
See also AscStr, StrLn, and variable LnDestPtr
Example Similar to the example in StrAsc.
Chapter 2, Procedures and Functions Page 10
STRG Utilities Reference Guide, Version 6.1b
---------------------------------------------------------------------------
LoCase function Strg
---------------------------------------------------------------------------
Function Converts characters to lower case.
Declaration LoCase (C: char)
Result type char
Remarks As the complement of UpCase, this routine converts
characters in the range A..Z to lower case.
See also ChrReplI, StrLwr, StrUpr, UpCase
---------------------------------------------------------------------------
Pos function Strg
---------------------------------------------------------------------------
Function Finds the position of a substring in a string.
Declaration Pos (Find,S: string)
Result type integer
Remarks It's the exact replacement of the System.Pos procedure, but
automatically replaces it with one that is up to 340%
faster.
Rating 24,100 str/sec
See also ChrPos*, StrBrk, StrPos*, Compiler reference manual.
---------------------------------------------------------------------------
StrAsc procedure Strg
---------------------------------------------------------------------------
Function Creates Pascal strings from ASCIIZ-type strings.
Declaration StrAsc (VAR Dest: string; VAR AscSrc; MaxLen: byte)
Remarks After StrAsc is executed, the global variable AscSrcPtr
points to the next ASCIIZ string skipping over any null
character. Should the conversion be truncated with MaxLen,
StrAsc makes sure that AscSrcPtr points to the next string
and not a null. Source and destination can be the same. As
in all move-type procedures, it is important to make sure
the destination size is sufficient to fit the source.
Rating 17,000 str/sec
See also StrLn, AscStr
Example Disassemble a sequential array of ASCIIZ strings into three
Pascal strings:
uses strg;
const
A: array[0..26] of char =
'Eagle'#00'Performance'#00'Software'#00;
var
S: array[0..4] of string;
i: byte;
begin
AscSrcPtr := @A;
for i:=1 to 3 do
StrAsc (S[i],AscSrcPtr^,255);
end.
The resulting strings would look like:
Chapter 2, Procedures and Functions Page 11
STRG Utilities Reference Guide, Version 6.1b
S[1] := 'Eagle';
S[2] := 'Performance';
S[3] := 'Software';
---------------------------------------------------------------------------
StrLn procedure Strg
---------------------------------------------------------------------------
Function Creates Pascal strings from ASCII TEXT strings.
Declaration StrLn (VAR Dest: string; VAR LnSrc; MaxLen: byte)
Remarks ASCII text file lines by definition end with a CR (#13) or a
CR/LF (#13/#10). StrLn searches for the CR and copies the
string prior to that character. After StrLn is executed,
the global variable LnSrcPtr points to the next line
skipping over any CR or LF even if the string is truncated
with MaxLen. Source and destination can be the same for
non-sequential conversions. As in all move-type procedures,
it is important to make sure the destination size is
sufficient to fit the source.
Suggestions The use of ReadLn for text files is disk intensive. StrLn
can be used together with BlockRead for extremely fast text
file operations.
Rating 16,800 str/sec
See also AscStr, LnStr, and variable LnSrcPtr
Example Similar to the example in AscStr.
---------------------------------------------------------------------------
Str* function Strg
---------------------------------------------------------------------------
Function Converts numbers to a string representation.
Declaration StrC (C: comp):
StrCF (C: comp; Field: integer)
StrCFD (C: comp; Field,Decimals: integer)
StrD (D: double)
StrDF (D: double; Field: integer)
StrDFD (D: double; Field,Decimals: integer)
StrE (E: extended)
StrEF (E: extended; Field: integer)
StrEFD (E: extended; Field,Decimals: integer)
StrL (L: longint)
StrLF (L: longint; Field: integer)
StrR (R: real)
StrRF (R: real; Field: integer)
StrRFD (R: real; Field,Decimals: integer)
StrS (S: single)
StrSF (S: single; Field: integer)
StrSFD (S: single; Field,Decimals: integer)
Result type string
Remarks These functions use the System.Str procedure, but have been
converted to a function form for convenience. Although they
are a fraction slower, they save code in the long run. The
IEEE reals are included only if the N/E compiler directives
are appropriately set for your use.
Rating Varies: uses System.Str.
Chapter 2, Procedures and Functions Page 12
STRG Utilities Reference Guide, Version 6.1b
See also StrBin, StrHex
---------------------------------------------------------------------------
StrBin function Strg
---------------------------------------------------------------------------
Function Converts numbers to binary strings.
Declaration StrBin (Num: longint; Field: byte)
Result type string
Remarks If the field is larger than the resulting string, the field
is balanced with leading zeros. If no leading zeros are
desired, set Field to 0. Maximum field is 32.
Rating 13,300 str/sec
See also StrHex, ValBin, ValHex
Example In the following examples, the results will be String1=
'0000111111' and String2='111111'.
MyByte := 63;
String1 := StrBin (MyByte,10);
String2 := StrBin (MyByte,3);
---------------------------------------------------------------------------
StrBrk function Strg
---------------------------------------------------------------------------
Function Finds first character that is a member of a group of chars.
Declaration StrBrk (S,Breaks: string; Index: byte)
Result type byte
Remarks Breaks (Brk) is a group of characters. The function returns
the index of the first character found to be a member of
Breaks moving RIGHT from the given index. Routine has fully
scanned when resulting index is zero. This routine is
usually used to parse a string. For greater speed, place
the most commonly used members early in Breaks.
Rating 1-char Breaks: 23,700 str/sec
5-char Breaks: 5,400 str/sec
See also ChrPos*, StrMemb, StrPosX, StrSpn
Example Find the position of the number in the string S:
var
S,Numbers: string;
Position: byte;
begin
S := 'Balance $24567.00';
StrEnum (Numbers,'0','9');
Position := StrBrk (S,Numbers,1); { Position=10 }
end.
---------------------------------------------------------------------------
StrCat* procedure Strg
---------------------------------------------------------------------------
Function Appends one string or substring to the end of another.
Declaration StrCat (VAR Dest: string; S: string; MaxLen: byte)
StrCatX (VAR Dest: string; S: string;
indeX,Count,MaxLen: byte)
Remarks This procedure appends the end of string Dest with S for a
Chapter 2, Procedures and Functions Page 13
STRG Utilities Reference Guide, Version 6.1b
maximum length limit of MaxLen. StrCat concatenates a full
string while StrCatX does a substring. This greatly speeds
up concatenation. Usually the SizeOf function is used for
MaxLen, or 255 can be used if there is no concern. Like
Concat, but up to 5 times faster.
Rating 44,100 str/sec
See also StrCopy, StrMove, StrOvr
Example Given S1='Eagle ' and S2='Performance', try the following:
StrCatX (S1,S2,7,3,255); ( S1='Eagle man' }
StrCut (S1,6); { S1='Eagle ' }
StrCat (S1,S2,255); { S1='Eagle Performance' }
---------------------------------------------------------------------------
StrCmp* function Strg
---------------------------------------------------------------------------
Function Compares one substring to another.
Declaration StrCmp (S1,S2: string; Index1,Index2,MaxLen: byte)
StrCmpI (S1,S2: string; Index1,Index2,MaxLen: byte)
Result type shortint
Result value After comparison, here are the possible values:
-1: S1<S2
0: S1=S2
+1: S1>S2
Remarks This routine compares (Cmp) two strings and determines Less
Than, Equal, or Greater Than. The comparison is made
between the resulting substrings starting at each
corresponding index and moving to the right. The indexes
are not adjusted should they extend beyond the end of string
at which the substring is considered null. The indexes of
difference are saved in the global variables CmpIndex1 and
CmpIndex2 which are 0 if the two substrings are equal.
StrCmp matches case while StrCmpI ignores case.
Rating StrCmp: 27,800 str/sec
StrCmpI: 4,600 str/sec
Example The following comparison of dates yields -1, CmpIndex1=13
and CmpIndex2=19.
S1 := 'MyEvent 90-04-23';
S2 := 'Second event: 90-05-17';
MyShortInt := StrCmp (S1,S2,9,15,8);
---------------------------------------------------------------------------
StrCopy procedure Strg
---------------------------------------------------------------------------
Function Directly copies a substring to create a new string.
Declaration StrCopy (VAR Dest: string; S: string; Index,Count: byte)
Remarks This is a move procedure for strings. Being a procedure
rather than a function, it is up to 3.3 times faster than
System.Copy. But be sure the Dest is large enough.
Rating 47,000 str/sec
See also Copy, StrCat, StrOvr
Example The following example extracts the substring 'target'.
Chapter 2, Procedures and Functions Page 14
STRG Utilities Reference Guide, Version 6.1b
S1 := 'This is the target word';
StrCopy (S2,S1,13,6); { S2='target' }
---------------------------------------------------------------------------
StrCut procedure Strg
---------------------------------------------------------------------------
Function Truncates a string above a maximum size.
Declaration StrCut (VAR S: string; MaxLen: byte)
Rating 430,000 str/sec
See also ChrDel*
Example Try the following code:
S := 'Eagle Performance Software';
StrCut (S,17); { S='Eagle Performance' }
---------------------------------------------------------------------------
StrDeTab procedure Strg
---------------------------------------------------------------------------
Function Expands all tabs to spaces at a given tab spacing.
Declaration StrDeTab (VAR Dest: string; S: string; TabSpaces: byte)
Remarks This routine expands all tabs to spaces given the tab
spacing. Source and Dest can be the same address. Position
1 is the first tab setting. Be sure Dest can handle the
expansion. Strings are truncated at 255.
Rating 7,700 str/sec
See also StrReTab
Example Expand the tabs (#9) in the following string:
S := #9'Col 9'#9'Col 17';
StrReTab (S,S,8); { S=' Col 9 Col 17' }
{ 1234567890123456789012 }
---------------------------------------------------------------------------
StrEnum procedure Strg
---------------------------------------------------------------------------
Function Enumerates a string of characters from First to Last.
Declaration StrEnum (VAR S: string; First,Last: char)
Remarks Enumeration can be increasing or decreasing, but do not wrap
through #00. Be sure the destination is large enough.
Strings are truncated at 255.
Rating 13,300 str/sec
See also StrFill, StrRev, StrSort
Example Try the following examples:
StrEnum (S,'a','f'); { S='abcdeg' }
StrEnum (T,'f','a'); { T='fedcba' }
---------------------------------------------------------------------------
StrFill procedure Strg
---------------------------------------------------------------------------
Function Fills a string with multiple copies of a substring.
Declaration StrFill (VAR S: string; Fill: string; Count,MaxLen: byte)
Remarks The fill overwrites S with concatenated copies of Fill. A
special option is built in for single character fills to be
Chapter 2, Procedures and Functions Page 15
STRG Utilities Reference Guide, Version 6.1b
extremely fast. Source and destination can be the same.
Strings are truncated by MaxLen.
Rating 1-char fill: 44,400 str/sec
5-char fill: 13,300 str/sec
See also ChrFill, StrEnum
Example Try the following examples:
StrFill (S,'a',5,255); { S='aaaaa' }
StrFill (T,'Fast',3,11); { T='FastFastFas' }
---------------------------------------------------------------------------
StrHex procedure Strg
---------------------------------------------------------------------------
Function Converts numbers to hex strings.
Declaration StrHex (Num: longint; Field: byte)
Remarks If the field is larger than the resulting string, the
field is balanced with leading zeros. If no leading zeros
are desired, set Field to 0. Maximum field is 8. No
leading '$' character is inserted.
Rating 25,100 str/sec
See also StrBin, ValBin, ValHex
Example Try the following examples:
MyWord := 4095;
String1 := StrHex (MyWord,5); { String1='00FFF' }
String2 := StrHex (MyWord,1); { String2='FFF' }
String3 := StrHex (MyWord,15); { String3='00000FFF' }
---------------------------------------------------------------------------
StrIns procedure Strg
---------------------------------------------------------------------------
Function Inserts a substring at a given index.
Declaration StrIns (VAR Dest: string; S: string; DestIndex,MaxLen: byte)
Remarks The routine is processed as if the insertion was done and
the resulting string truncated after MaxLen. DestIndex is
adjusted to the minimum of DestIndex and Dest[0]. The
operation is skipped if MaxLen<DestIndex or S[0]=0. Up to
5 times faster than System.Insert.
Rating 31,900 str/sec
See also StrCat, StrCopy
Example Try the following examples:
S := 'Hello friends';
J := 'Jim';
Index := 7; { 123456789012345678 }
StrIns (S,'my ',Index,255); { S='Hello my friends' }
Since StrIns lets you control MaxLen, the following line of
code:
StrIns (S,J,Index,pred(Index)+length(J));
Is the same as the following two lines:
Chapter 2, Procedures and Functions Page 16
STRG Utilities Reference Guide, Version 6.1b
StrCut (S,pred(Index)); { 123456789 }
StrCat (S,J,255); { S='Hello Jim' }
---------------------------------------------------------------------------
StrJ* function Strg
---------------------------------------------------------------------------
Function Left, center, or right justifies a string in a field of
spaces.
Declaration StrJC (S: string; Field: byte) { Justify center }
StrJL (S: string; Field: byte) { Justify left }
StrJR (S: string; Field: byte) { Justify right }
Result type string
Remarks If the field is smaller than the source string, the string
is simply returned unaltered. These routines save from
recopying the string in the stack making it faster.
Rating 17,500 str/sec
See also ChrPad*, StrOvr
Example Try the following examples:
S := StrJC ('test',7); { S=' test ' }
S := StrJL ('test',7); { S='test ' }
S := StrJR ('test',7); { S=' test' }
---------------------------------------------------------------------------
StrLwr procedure Strg
---------------------------------------------------------------------------
Function Converts strings to lower case.
Declaration StrLwr (VAR S: string)
Remarks The operation works on the entire string.
Rating 8,900 str/sec
See also ChrReplI, LoCase, StrUpr, UpCase
---------------------------------------------------------------------------
StrMemb procedure Strg
---------------------------------------------------------------------------
Function Reduces a string to its membership in ascending order.
Declaration StrMemb (VAR Dest: string; S: string)
Remarks Membership is the list of characters that occur in a string.
Only one character is listed in the destination string for
any number of the same character in the source string.
Source and destination may be the same. This is useful when
repeated scans are used on the same string for speed.
Rating 4,500 str/sec
See also Is*, StrBrk, StrSort, StrSpn
Example Try the following example:
var
S1,S2: string;
begin
S1 := 'Eagle Performance Software 321';
StrMemb (S2,S1); { S2=' 123EPSacefglmnortw' }
end.
Chapter 2, Procedures and Functions Page 17
STRG Utilities Reference Guide, Version 6.1b
---------------------------------------------------------------------------
StrMove procedure Strg
---------------------------------------------------------------------------
Function Moves a string to another location WITH the length byte.
Declaration StrMove (VAR Dest: string; S: string)
Remarks It's up to 70% faster than using and assignment (":="). Use
when speed is essential. Be sure Dest is large enough.
Rating 53,400 str/sec
See also StrCat, StrCopy, StrOvr, StrPeek
Example Assign a string to another:
S1 := 'Now is the time';
StrMove (S2,S1); { S2='Now is the time' }
---------------------------------------------------------------------------
StrOvr procedure Strg
---------------------------------------------------------------------------
Function Overwrites a string at a given index.
Declaration StrOvr (VAR Dest: string; S: string; Index: byte)
Remarks The length of the original string is increased if the
substring makes it longer. Any gap between the two
strings is filled with spaces. This is a move-type
procedure, so be sure the destination is large enough.
However, resulting strings are truncated at 255.
Suggestions This is a popular routine. Use it when strings need to be
aligned for formatting or displayed in columns.
Rating 44,100 str/sec
See also Copy, StrCat, StrCopy, StrJ*, StrMove, StrPoke
Example Try the following examples:
S := 'Hello world';
StrOvr (S,'friends',7); { S='Hello friends' }
T := 'First'; { 123456789012345678 }
StrOvr (T,'MI' , 9); { T='First MI' }
StrOvr (T,'Last',15); { T='First MI Last' }
---------------------------------------------------------------------------
StrPeek procedure Strg
---------------------------------------------------------------------------
Function Grabs an array in memory and converts it to a string.
Declaration StrPeek (VAR Dest: string; VAR Source; Count: byte)
Remarks Takes an array in memory at Source and converts it to a
string at Dest. Dest[0] cannot overlap Source. This allows
arrays to be handled as strings.
Rating 42,100 str/sec
See also StrMove, StrPoke
Example Try the following example:
Chapter 2, Procedures and Functions Page 18
STRG Utilities Reference Guide, Version 6.1b
const { 12345678901234567890123 }
A: array[1..23] of char = 'Eagle Performance, Inc.';
var
S: string;
begin
StrPeek (S,A[7],11); { S='Performance' }
end.
---------------------------------------------------------------------------
StrPoke procedure Strg
---------------------------------------------------------------------------
Function Pokes the characters of a string into memory.
Declaration StrPoke (VAR Dest; S: string)
Remarks Pokes the characters of S as an array into memory NOT
including the length byte. This allows strings to be
handled as arrays. Dest[0] cannot overlap S.
Rating 43,600 str/sec
See also StrOvr, StrPeek
Example Try the following example:
const { 12345678901234567890123 }
A: array[1..23] of char = 'Eagle , Inc.';
S: string = 'Performance';
begin { 12345678901234567890123 }
StrPoke (A[7],S); { A='Eagle Performance, Inc.' }
end.
---------------------------------------------------------------------------
StrPos* function Strg
---------------------------------------------------------------------------
Function Finds the position of a given string with match/ignore case.
Declaration StrPosL (S,Find: string; Nth: byte)
StrPosLI (S,Find: string; Nth: byte)
StrPosR (S,Find: string; Nth: byte)
StrPosRI (S,Find: string; Nth: byte)
StrPosX (S,Find: string; indeX: byte)
StrPosXI (S,Find: string; indeX: byte)
Result type byte
Remarks Using suffixes, -L routine searches from the left while the
-R searches from the right for the Nth occurrence. The -X
routine starts at the given index and searches right for the
first occurrence. These routines match case, while those
with the added -I suffix will Ignore case.
Rating StrPos? 1-char: 23,900 str/sec
StrPos? 5-char: 18,200 str/sec
StrPos?I 1-char: 6,800 str/sec
StrPos?I 5-char: 5,900 str/sec
See also ChrPos*, StrBrk
Example Find the position of the following substrings:
{ 1234567890123456789012345678901234 }
S1 := 'Write excellent routines and Excel';
MyByte := StrPosL (S1,'exc',1); { MyByte=7 }
MyByte := StrPosLI (S1,'exc',2); { MyByte=30 }
Chapter 2, Procedures and Functions Page 19
STRG Utilities Reference Guide, Version 6.1b
MyByte := StrPosR (S1,'exc',1); { MyByte=7 }
MyByte := StrPosRI (S1,'exc',2); { MyByte=7 }
MyByte := StrPosX (S1,'exc',4); { MyByte=7 }
MyByte := StrPosXI (S1,'EXC',4); { MyByte=7 }
---------------------------------------------------------------------------
StrQty* function Strg
---------------------------------------------------------------------------
Function Counts the occurrences of a given substring in
a string with match/ignore case.
Declaration StrQty (S,Find: string)
StrQtyI (S,Find: string)
Result type byte
Remarks StrQty matches case while StrQtyI ignores case.
Rating StrQty 1-char: 23,900 str/sec
StrQty 5-char: 18,200 str/sec
StrQtyI 1-char: 6,800 str/sec
StrQtyI 5-char: 5,900 str/sec
See also ChrQty*, WrdQty
---------------------------------------------------------------------------
StrRepl* procedure Strg
---------------------------------------------------------------------------
Function Finds and replaces a substring from a given index for Qty
number of replacements with match/ignore case.
Declaration StrRepl (VAR S: string; Find,Repl: string;
Index,Qty,MaxLen: byte)
StrReplI (VAR S: string; Find,Repl: string;
Index,Qty,MaxLen: byte)
Remarks The operation starts from Index and goes to the right. It
will stop if the index is beyond the end of string or it has
replaced as many as it can. StrRepl matches case while
StrReplI ignores case.
The global variable ReplToDo is the result of Qty less the
number of replacements that were done on the string.
MaxLen is used for the special case when the length of
Repl is greater than Find. The routine will replace as many
as it can. If one more replacement would cause the string
length to be greater than MaxLen, the routine will stop at
that find and report the index as ReplIndex and will set
ReplOverFlow=true. Otherwise, ReplIndex=0 and ReplOverFlow
is false.
Rating StrRepl: 8,800 str/sec
StrReplI: 4,600 str/sec
See also ChrDel*, ChrRepl*
Example Try the following example:
var
S: string;
begin
{ 1234567890123456789012345678901234 }
S := 'Fast TEST String, FAST test string';
StrReplI (S,'st','---',1,255,38);
Chapter 2, Procedures and Functions Page 20
STRG Utilities Reference Guide, Version 6.1b
end.
The results will be ReplOverFlow=true, ReplIndex=30, and
ReplToDo=251 with S as follows:
{ 12345678901234567890123456789012345678 }
S := 'Fa--- TE--- ---ring, FA--- test String';
---------------------------------------------------------------------------
StrReTab procedure Strg
---------------------------------------------------------------------------
Function Reduces spaces to tabs.
Declaration StrReTab (VAR Dest: string; S: string; TabSpaces: byte)
Remarks This routine reduces spaces with tabs given the tab spacing.
Embedded tabs are accounted for. Tab spacing is a minimum
of one and zero values are forced to 1. Position 1 is
considered column 1. Source and Dest can be the same
address.
Rating 6,000 str/sec
See also StrDeTab
Example Reduce spaces in the following string:
{ 1234567890123456789012 }
S := ' Col 9 Col 17';
StrDeTab (S,S,8); { S=#9'Col 9'#9'Col 17' }
---------------------------------------------------------------------------
StrRev procedure Strg
---------------------------------------------------------------------------
Function Reverses the order of the characters in a string.
Declaration StrRev (VAR S: string)
Rating 16,600 str/sec
See also StrEnum, StrSort
Example Try the following:
S := 'abcdefg';
StrRev (S); { S='gfedcba' }
---------------------------------------------------------------------------
StrRoll procedure Strg
---------------------------------------------------------------------------
Function Rolls the characters in a string forward or backward.
Declaration StrRoll (VAR S: string; Count: integer)
Remarks A forward roll moves characters from right to left and
appends the rolled out characters on the right end. A
backward roll (a negative value) does the reverse. If Count
is greater than S[0], the Count is adjusted by mod.
Rating 27,800 str/sec
See also StrRev, StrSort
Example Try the following:
S1 := '1234567890'; S2:=S1;
StrRoll (S1,2); { S1='3456789012' }
StrRoll (S2,-2); { S2='9012345678' }
Chapter 2, Procedures and Functions Page 21
STRG Utilities Reference Guide, Version 6.1b
---------------------------------------------------------------------------
StrSort procedure Strg
---------------------------------------------------------------------------
Function Operates on a string by sorting it in ascending order.
Declaration StrSort (VAR S: string)
Remarks Two algorithms are used for this routine for speed. For
strings up to 22 chars long, the classic Quick Sort is used.
After 22 chars, the Tally Sort is used which is up to 10
times faster than Quick Sort, because the Tally Sort does it
in only two passes.
Rating 3,600 str/sec
See also StrEnum, StrMemb, StrRev
Suggestions This routine is so efficient, you can even use it to sort
any byte arrays by using an absolute variable at the address
you want to sort or you can use StrPeek/StrPoke for arrays
up to 255 bytes.
Example Try the following:
S := 'fgb1edca';
StrSort (S); { S='1abcdefg' }
---------------------------------------------------------------------------
StrSpn function Strg
---------------------------------------------------------------------------
Function Counts the number of consecutive characters that are all
members of a group of chars.
Declaration StrSpn (S,Members: string; Index: byte)
Result type byte
Remarks The function scans the string S starting at Index and scans
RIGHT. Members is any group of characters. As long as the
scanned character is in Members, it will continue to scan
for the next one until it finds a non-member of Members.
The result is the span (Spn) of the substring that are all
members. This routine is usually used to parse a string.
For greater speed, place the most commonly used members
early in Members.
Rating 1-char Members: 23,600 str/sec
5-char Members: 3,600 str/sec
See also StrBrk, StrMemb, Wrd*, WrdParse, WrdToken
Example Find the length of the number in string S:
var
S,Numbers: string;
Size: byte;
begin
S := 'Balance $24,567.00 in credits.';
StrEnum (Numbers,'0','9');
StrCat (Numbers,'+-.,',255);
Size := StrSpn (S,Numbers,10); { Size=9 }
end.
Chapter 2, Procedures and Functions Page 22
STRG Utilities Reference Guide, Version 6.1b
---------------------------------------------------------------------------
StrUpr procedure Strg
---------------------------------------------------------------------------
Function Converts strings to upper case.
Declaration StrUpr (VAR S: string)
Remarks The operation works on the entire string.
Rating 8,900 str/sec
See also ChrReplI, LoCase, StrLwr, UpCase
---------------------------------------------------------------------------
UpCase function Strg
---------------------------------------------------------------------------
Function Converts characters to upper case.
Declaration UpCase (C: char)
Result type char
Remarks It's about 3 times faster than System.UpCase producing
identical results.
See also ChrReplI, LoCase, StrLwr, StrUpr
---------------------------------------------------------------------------
ValBin function Strg
---------------------------------------------------------------------------
Function Converts binary strings to longint.
Declaration ValBin (S: string; VAR Code: integer)
Result type longint (but smaller types are permissible)
Remarks ValBin has these superior features:
- Leading spaces are permitted but not trailing ones.
- Leading zeros are also permitted.
- A non-zero error code points to the invalid character in
the string.
- Numbers larger than $FFFFFFFF produce an error.
- ValBin salvages a value even if there is an error!
- Routine is more flexible as a function rather than being
similar to the Val procedure which is compiler dependent
on the number type.
Rating 25,500 str/sec
See also StrBin, StrHex, ValHex
Example In the last example, Code=9. The others set Code=0.
LongInt1 := ValBin ('001100100',Code); { LontInt1=100 }
LongInt2 := ValBin ('111110100',Code); { LongInt2=500 }
LongInt3 := ValBin (' 101101b',Code); { LongInt3=45 }
---------------------------------------------------------------------------
ValHex function Strg
---------------------------------------------------------------------------
Function Converts hex strings to longint.
Declaration ValHex (S: string; VAR Code: integer)
Result type longint (but smaller types are permissible)
Remarks ValHex has these superior features:
- Leading spaces are permitted but not trailing ones.
Chapter 2, Procedures and Functions Page 23
STRG Utilities Reference Guide, Version 6.1b
- Leading zeros are also permitted.
- The leading '$' is optional!
- A non-zero error code points to the invalid character in
the string.
- Numbers larger than $FFFFFFFF produce an error.
- ValHex salvages a value even if there is an error!
- Twice as fast as Val and uses much less code.
- Routine is more flexible as a function rather than the
Val procedure which is compiler dependent on the number
type.
Rating 27,200 str/sec
See also StrBin, StrHex, ValBin
Example In the last example, Code=5. The others set Code=0.
LongInt1 := ValHex (' 0064',Code); { LongInt1=100 }
LongInt2 := ValHex (' $1f4',Code); { LongInt1=500 }
LongInt3 := ValHex (' 2Dh',Code); { LongInt1=45 }
---------------------------------------------------------------------------
Wrd* procedure Strg
---------------------------------------------------------------------------
Function Parses words separated by spaces.
Declaration WrdL (VAR Dest: string; S: string; Nth: byte)
WrdR (VAR Dest: string; S: string; Nth: byte)
WrdLX (VAR Dest: string; S: string; indeX: byte)
WrdRX (VAR Dest: string; S: string; indeX: byte)
Remarks A word at the beginning or end of a string is considered a
word even though it does not have spaces on both ends. The
procedures apply as follows:
WrdL - parses Nth word from the Left.
WrdR - parses Nth word from the Right.
WrdLX - parses first word from Left starting at indeX.
WrdRX - parses first word from Right starting at indeX.
WrdLX and WrdRX parses the first word with its first letter
found in the direction of search even if it starts at indeX.
Rating Wrd?: 16,400 str/sec
Wrd?X: 25,100 str/sec
See also StrBrk, StrSpn, WrdPos*, WrdParse, WrdToken
Example Try the following parsing:
var S,W1,W2,W3,W4: string;
begin
S := 'Eagle Performance Software Products';
WrdL (W1,S,2); { W1='Performance'}
WrdR (W2,S,2); { W2='Software' }
WrdLX (W3,S,2); { W3='Performance'}
WrdRX (W4,S,255); { W1='Products' }
end.
Chapter 2, Procedures and Functions Page 24
STRG Utilities Reference Guide, Version 6.1b
---------------------------------------------------------------------------
WrdParse procedure Strg
---------------------------------------------------------------------------
Function Parses substrings separated by individual delimiters.
Declaration WrdParse (VAR Dest: string; S,Delims: string;
VAR Index: byte)
Remarks Delims is a group of characters considered delimiters.
(Place the most used delimiters early in the string for
faster performance.) WrdParse extracts the next delimited
word RIGHT from the given Index and does not search
backwards. WrdParse adjusts Index so it marks where to
start the next parse on the next call. Routine has fully
scanned when resulting indeX is set to zero. Different from
WrdToken, nulls are significant; i.e., two delimiters in
sequence is considered a null parse. So, if a delimiter is
at the end of a string, the final parse returned is null.
Rating 1-char Delims: 28,500 str/sec
5-char Delims: 6,500 str/sec
See also StrBrk, StrSpn, Wrd*, WrdPos*, WrdToken
Example Parse the following string S into the string array:
uses strg;
var
A: array[0..4] of string;
i,j,Index: byte;
D,S: string;
begin
S := 'Faster, yet better';
D := ' ,.'; { These are the delimiters. }
i := 0; { First parse will be in Sarray[0] }
Index := 1; { Start at first character }
while Index<>0 do
begin
WrdParse (A[i],S,D,Index);
inc (i);
end;
end.
Program will end with i=4 which is the number of parses
found. The results are A[0]='Faster', A[1]='', A[2]='yet',
and A[3]='better'. A[1] is null because a null string was
parsed between the comma and space which is useful for
parsing command line entries that are null.
---------------------------------------------------------------------------
WrdPos* function Strg
---------------------------------------------------------------------------
Function Returns position of word delimited by spaces.
Declaration WrdPosL (S: string; Nth: byte)
WrdPosR (S: string; Nth: byte)
WrdPosLX (S: string; indeX: byte)
WrdPosRX (S: string; indeX: byte)
Result type byte
Remarks A word at the beginning or end of a string is considered a
Chapter 2, Procedures and Functions Page 25
STRG Utilities Reference Guide, Version 6.1b
word even though it does not have spaces on both ends. The
procedures apply as follows:
WrdPosL - find Nth word from the Left
WrdPosR - find Nth word from the Right
WrdPosLX - find first word from Left starting at indeX.
WrdPosRX - find first word from Right starting at indeX.
If the index is not located on the first letter of a word,
WrdPosLX and WrdPosRX will continue scanning for the next
word.
Rating WrdPos?: 17,700 str/sec
WrdPos?X: 26,400 str/sec
See also StrBrk, StrSpn, Wrd*, WrdParse, WrdToken
Example Try the following examples:
{ 12345678901234567890123456789012345678 }
S := 'Now is the time for all good programs.';
MyByte := WrdPosR (S,1); { MyByte=30 }
MyByte := WrdPosL (S,3); { MyByte= 8 }
MyByte := WrdPosLX (S,9); { MyByte=12 }
MyByte := WrdPosRX (S,9); { MyByte= 8 }
---------------------------------------------------------------------------
WrdQty function Strg
---------------------------------------------------------------------------
Function Counts the number of words in a string delimited by spaces.
Declaration WrdQty (S: string)
Result type byte
Remarks A word at the beginning or end of a string is considered a
word even though it does not have spaces on both ends.
Rating 18,400 str/sec
See also ChrQty*, StrQty*
Example Try the following example:
S := 'Now is the time for all good programs.';
MyByte := WrdQty (S); { MyByte=8 }
---------------------------------------------------------------------------
WrdToken procedure Strg
---------------------------------------------------------------------------
Function Parses substrings separated by groups of delimiters.
Declaration WrdToken (VAR Dest: string; S,Delims: string;
VAR indeX: byte)
Remarks Delims is a group of characters considered delimiters.
(Place the most used delimiters early in the string for
faster performance.) WrdToken extracts the next delimited
word RIGHT from the given indeX and does not search
backwards. WrdToken adjusts indeX so it marks where to
start the next parse on the next call. Routine has fully
scanned when resulting indeX is set to zero. Different from
WrdParse, nulls are NOT significant; i.e., all delimiters
are passed over until the next token is found. But, if a
delimiter is at the end of a string, the final token
Chapter 2, Procedures and Functions Page 26
STRG Utilities Reference Guide, Version 6.1b
returned is still null.
Rating 1-char Delims: 28,500 str/sec
5-char Delims: 6,500 str/sec
See also StrBrk, StrSpn, Wrd*, WrdPos*, WrdParse
Example Parse the following S into the string array:
uses strg;
var
A: array[0..4] of string;
i,j,Index: byte;
D,S: string;
begin
S := 'Faster, yet better';
D := ' ,.'; { These are the delimiters. }
i := 0; { First parse will be in A[0] }
Index := 1; { Start at first character }
while Index<>0 do
begin
WrdToken (A[i],S,D,Index);
inc (i);
end;
end.
Program will end with i=3 which is the number of tokens
found. The results are A[0]='Faster', A[1]='yet', and
A[2]='better'.
Chapter 2, Procedures and Functions Page 27
STRG Utilities Reference Guide, Version 6.1b
3. V A R I A B L E S
There are only a few variables to consider in the STRG unit. Some can be
accessed for global use and just one is local.
GLOBAL
Global Variables - These variables can be used to assist your programs more
efficiently:
Variable Description
------------ -----------------------------------------------------------
AscDestPtr (Type: Pointer) After AscStr is executed, this pointer
points to the next ASCIIZ destination after the end-of-
string null. This is very useful for sequential
conversions to save space with ASCIIZ strings.
AscSrcPtr (Type: Pointer) After StrAsc is executed, this pointer
points to the next ASCIIZ source after the end-of-string
null or the next valid character if the conversion is
limited by MaxLen. This is very useful for sequential
conversions from contiguous ASCIIZ strings.
CmpIndex1 (Type: Integer) After strings are compared with StrCmp*,
the index of difference for S1 is saved in this variable.
The integer type is used in lieu of byte for the case of
difference at column 256 (Index1+MaxLen>255). If you do
not use strings out to S1[255], then it is permissible to
use byte assignments to this variable.
CmpIndex2 (Type: Integer) Same as CmpIndex1 except it applies to S2.
LnDestPtr (Type: Pointer) After LnStr is executed, this pointer
points to the next ASCII text file destination after the
end-of-string CR/LF. This is very useful for sequential
conversions to an ASCII text file for a block write.
LnSrcPtr (Type: Pointer) After StrLn is executed, this pointer
points to the next ASCII text file source after the end-of-
string CR/LF, CR, or the next valid character if the
conversion is limited by MaxLen. This is very useful for
sequential conversions from a block read of an ASCII text
file.
ReplIndex (Type: Byte) After using StrRepl* and there is an
overflow, this variable provides the index where the
operation was halted.
ReplOverFlow (Type: Boolean) After using StrRepl* when the replacement
string is longer than the find string and the resulting
string would be longer than MaxLen permits, this value is
set to TRUE. This means the operation went as far as it
could go before overflowing the length.
Chapter 3, Variables Page 28
STRG Utilities Reference Guide, Version 6.1b
ReplToDo (Type: Byte) After using StrRepl*, this variable indicates
how many replacements are still needed to fulfill the
original request. If it is zero, then all replacements
were done.
LOCAL
Local Constant - There is only one local constant to STRG:
Constant Description
------------ -----------------------------------------------------------
ChrClass (Type: array of char) Several of the more complicated Is*
functions use this 128 char array to quickly classify
characters by testing individual bits in the array.
Simpler Is* functions do not use this array and it is
optimized out of the program.
Chapter 3, Variables Page 29
STRG Utilities Reference Guide, Version 6.1b
4. A C C E S S I B L E M E M O R Y
Many of the routines in STRG use 16-bit transfers to increase string
processing. As as you program to normally to RAM, these routines will work
fine. Just remember that certain hardware other than RAM can have
limitations. The only one of which we are aware is trying to use these
routines for direct manipulation of the EGA/VGA bit plane memory for video
graphics, which would indeed be a bizarre application for these routines.
For graphics programming, either stick to the BGI drivers, or use routines
that only have 8-bit transfers. For more info on this limitation on video
hardware, check out page 114 of Richard Wilton's book "Programmer's Guide
to PC & PS/2 Video Systems".
Chapter 4, Accessible Memory Page 30
STRG Utilities Reference Guide, Version 6.1b
5. Q U I C K R E F E R E N C E
For a quick reference for all of the declarations contained in this unit,
the following are all the routines listed in alphabetical order.
procedure AscStr (VAR AscDest; S: string);
procedure ChrDel (VAR S: string; Find: char);
procedure ChrDelL (VAR S: string; Find: char);
procedure ChrDelR (VAR S: string; Find: char);
procedure ChrFill (VAR S: string; Fill: char; Count: byte);
procedure ChrPadC (VAR S: string; Find: char; Field: byte);
procedure ChrPadL (VAR S: string; Find: char; Field: byte);
procedure ChrPadR (VAR S: string; Find: char; Field: byte);
function ChrPosL ( S: string; Find: char; Nth: byte): byte;
function ChrPosLI ( S: string; Find: char; Nth: byte): byte;
function ChrPosR ( S: string; Find: char; Nth: byte): byte;
function ChrPosRI ( S: string; Find: char; Nth: byte): byte;
function ChrPosX ( S: string; Find: char; indeX: byte): byte;
function ChrPosXI ( S: string; Find: char; indeX: byte): byte;
function ChrQty ( S: string; Find: char): byte;
function ChrQtyI ( S: string; Find: char): byte;
procedure ChrRepl (VAR S: string; Find,Repl: char; Index,Qty: byte);
procedure ChrReplI (VAR S: string; Find,Repl: char; Index,Qty: byte);
function Copy ( S: string; Index,Count: integer): string;
procedure Delete (VAR S: string; Index,Count: integer);
function IsAlNum (C: char): boolean;
function IsAlpha (C: char): boolean;
function IsASCII (C: char): boolean;
function IsCntrl (C: char): boolean;
function IsDigit (C: char): boolean;
function IsDos (C: char): boolean;
function IsFile (C: char): boolean;
function IsGraph (C: char): boolean;
function IsLower (C: char): boolean;
function IsPath (C: char): boolean;
function IsPrint (C: char): boolean;
function IsPunct (C: char): boolean;
function IsReal (C: char): boolean;
function IsSigned (C: char): boolean;
function IsSpace (C: char): boolean;
function IsUpper (C: char): boolean;
function IsXDigit (C: char): boolean;
procedure LnStr (VAR LnDest; S: string);
function LoCase (C: char): char;
function Pos (Find,S: string): byte;
procedure StrAsc (VAR Dest: string; VAR AscSrc; MaxLen: byte);
function StrBin (Num: longint; Field: byte): string;
function StrBrk (S,Breaks: string; Index: byte): byte;
function StrC (C: comp): string;
procedure StrCat (VAR Dest: string; S: string; MaxLen: byte);
procedure StrCatX (VAR Dest: string; S: string; indeX,Count,MaxLen: byte);
function StrCF (C: comp; Field: integer): string;
function StrCFD (C: comp; Field,Decimals: integer): string;
function StrCmp (S1,S2: string; Index1,Index2,MaxLen: byte): shortint;
Chapter 5, Quick Reference Page 31
STRG Utilities Reference Guide, Version 6.1b
function StrCmpI (S1,S2: string; Index1,Index2,MaxLen: byte): shortint;
procedure StrCopy (VAR Dest: string; S: string; Index,Count: byte);
procedure StrCut (VAR S: string; MaxLen: byte);
function StrD (D: double): string;
procedure StrDeTab (VAR Dest: string; S: string; TabSpaces: byte);
function StrDF (D: double; Field: integer): string;
function StrDFD (D: double; Field,Decimals: integer): string;
function StrE (E: extended): string;
function StrEF (E: extended; Field: integer): string;
function StrEFD (E: extended; Field,Decimals: integer): string;
procedure StrEnum (VAR S: string; First,Last: char);
procedure StrFill (VAR S: string; Fill: string; Count,MaxLen: byte);
function StrHex (Num: longint; Field: byte): string;
procedure StrIns (VAR Dest: string; S: string; DestIndex,MaxLen: byte);
function StrJC (S: string; Field: byte): string;
function StrJL (S: string; Field: byte): string;
function StrJR (S: string; Field: byte): string;
function StrL (L: longint): string;
function StrLF (L: longint; Field: integer): string;
procedure StrLn (VAR Dest: string; VAR LnSrc; MaxLen: byte);
procedure StrLwr (VAR S: string);
procedure StrMemb (VAR Dest: string; S: string);
procedure StrMove (VAR Dest: string; S: string);
procedure StrOvr (VAR Dest: string; S: string; DestIndex: byte);
procedure StrPeek (VAR Dest: string; VAR Source; Count: byte);
procedure StrPoke (VAR Dest; S: string);
function StrPosL (S,Find: string; Nth: byte): byte;
function StrPosLI (S,Find: string; Nth: byte): byte;
function StrPosR (S,Find: string; Nth: byte): byte;
function StrPosRI (S,Find: string; Nth: byte): byte;
function StrPosX (S,Find: string; indeX: byte): byte;
function StrPosXI (S,Find: string; indeX: byte): byte;
function StrQty (S,Find: string): byte;
function StrQtyI (S,Find: string): byte;
function StrR (R: real): string;
procedure StrRepl (VAR S: string; Find,Repl: string; Index,Qty,MaxLen: byte);
procedure StrReplI (VAR S: string; Find,Repl: string; Index,Qty,MaxLen: byte);
procedure StrReTab (VAR Dest: string; S: string; TabSpaces: byte);
procedure StrRev (VAR S: string);
function StrRF (R: real; Field: integer): string;
function StrRFD (R: real; Field,Decimals: integer): string;
procedure StrRoll (VAR S: string; Count: integer);
function StrS (S: single): string;
function StrSF (S: single; Field: integer): string;
function StrSFD (S: single; Field,Decimals: integer): string;
procedure StrSort (VAR S: string);
function StrSpn (S,Members: string; Index: byte): byte;
procedure StrUpr (VAR S: string);
function UpCase (C: char): char;
function ValBin (S: string; VAR Code: integer): longint;
function ValHex (S: string; VAR Code: integer): longint;
procedure WrdL (VAR Dest: string; S: string; Nth: byte);
procedure WrdLX (VAR Dest: string; S: string; indeX: byte);
procedure WrdParse (VAR Dest: string; S,Delims: string; VAR Index: byte);
Chapter 5, Quick Reference Page 32
STRG Utilities Reference Guide, Version 6.1b
function WrdPosL (S: string; Nth: byte): byte;
function WrdPosLX (S: string; indeX: byte): byte;
function WrdPosR (S: string; Nth: byte): byte;
function WrdPosRX (S: string; indeX: byte): byte;
function WrdQty (S: string): byte;
procedure WrdR (VAR Dest: string; S: string; Nth: byte);
procedure WrdRX (VAR Dest: string; S: string; indeX: byte);
procedure WrdToken (VAR Dest: string; S,Delims: string; VAR Index: byte);
Chapter 5, Quick Reference Page 33